home *** CD-ROM | disk | FTP | other *** search
/ Technotools / Technotools (Chestnut CD-ROM)(1993).ISO / lang_c / mikecom / async.doc < prev    next >
Text File  |  1987-05-19  |  20KB  |  423 lines
  1.  
  2. *******************************************************************************
  3.                       ASYNC FUNCTIONS FOR MICROSOFT C
  4.                Mike Dumdei,  6 Holly Lane,  Texarkana TX  75503
  5. *******************************************************************************
  6.  
  7. These functions provide a library of interrupt driven communications routines
  8. for users of MicroSoft C versions 3 and 4.  They make calls to the MSC library
  9. functions 'malloc' and 'free' so if you want to modify them to work with a
  10. compiler other than MicroSoft's you will need to use your compiler's version
  11. of these functions.  The ASYNC.H header file sets up most of the segment names
  12. which should make conversion easier if you want to attempt it.
  13.  
  14. The routines support all memory models (small, compact, medium, large, and
  15. huge) and a library for any size model can be created using the included
  16. MAKE file 'A_LIB.NEW' and defining the model size desired. Ex:
  17.   make size=LARGE a_lib.new
  18. If a memory size is not given a SMALL lib is the default.  If you are not
  19. using make, you can assemble for different sizes using MASM by defining the
  20. memory model on the command line.  Ex:
  21.   masm async /dLARGE /mx;
  22.  
  23. COMM.H is an include file that contains the function decalarations and various
  24. definitions that apply to the ASYNC routines.
  25.  
  26.  
  27. DESCRIPTION OF FUNCTIONS:
  28.  
  29. -------------------------------------------------------------------------------
  30. ASYNC_CARRIER -- fast check for carrier detect present.
  31. -------------------------------------------------------------------------------
  32.   Example:
  33.     int         async_carrier(int);
  34.     rcode = async_carrier(port);
  35.  
  36.   Returns:
  37.     TRUE  (1)   - carrier was present
  38.     FALSE (0)   - no carrier detected
  39.     R_NOPORT    - the port hasn't been opened
  40.  
  41. To monitor carrier detect while transmitting, use this function to get the
  42. fastest executing code.  When receiving, for the fastest code, check the CD
  43. bit in the STAT1 byte which is returned with the character.  Async_stat also
  44. returns carrier detect status but is slightly slower than either of the above
  45. since it also gets some other information.  TRUE and FALSE are not defined
  46. in COMM.H.
  47.  
  48. -------------------------------------------------------------------------------
  49. ASYNC_CLOSE -- close a serial communications port.
  50. -------------------------------------------------------------------------------
  51.   Example:
  52.     int         async_close(int);
  53.     rcode = async_close(port);
  54.  
  55.   Returns:
  56.     R_OK        - close was successful
  57.     R_NOPORT    - the port hasn't been opened
  58.  
  59. This function closes an opened port.  All data in the buffers is lost.  The
  60. modem registers and the interrupt controller are returned to the state they
  61. were in when the port was opened.  This function makes a call to the MSC
  62. library function 'FREE'.
  63.  
  64.  
  65. -------------------------------------------------------------------------------
  66. ASYNC_DTR -- toggle DTR modem signal.
  67. -------------------------------------------------------------------------------
  68.   Example:
  69.     int         async_dtr(int, int);
  70.     rcode = async_dtr(port, flag);
  71.  
  72.   Returns:
  73.     R_OK        - operation was successful
  74.     R_NOPORT    - the port hasn't been opened
  75.  
  76. A zero flag will cause the modem signal 'Data Terminal Ready' to be brought
  77. to its FALSE state.  Often used to hang up the modem.  A non-zero flag
  78. re-enables the DTR signal.  The DTR signal is set to the TRUE condition when
  79. a port is first opened.
  80.  
  81.  
  82. -------------------------------------------------------------------------------
  83. ASYNC_MSR -- get the value of the modem status register.
  84. -------------------------------------------------------------------------------
  85.   Example:
  86.     int         async_msr(int);
  87.     msr_val = async_msr(port);
  88.  
  89.   Returns:
  90.     High byte = 0, low byte equals current contents of the MSR.
  91.     R_NOPORT    - the port hasn't been opened
  92.  
  93. This function does not actually read the modem status register.  That is done
  94. using the modem status interrupt function of the comm chip.  When a modem
  95. status interrrupt occurs the MSR is read and the value placed in a storage
  96. area.  This function returns the value from the storage area.
  97.  
  98. -------------------------------------------------------------------------------
  99. ASYNC_MSRFLOW -- set the mask for modem signals to be monitored while tx'ing.
  100. -------------------------------------------------------------------------------
  101.   Example:
  102.     int         async_msrflow(int, int);
  103.     rcode = async_msrflow(port, mask);
  104.  
  105.   Returns:
  106.     R_OK        - operation was successful
  107.     R_BADARG    - attempted to set bits in mask other than CTS, DSR, or CD
  108.     R_NOPORT    - the port hasn't been opened
  109.  
  110. Use this function to set the bit mask for the modem status signals that must be
  111. in the TRUE state for transmit interrupts to be active.  Signals that can be
  112. monitored are Clear to Send, Data Set Ready, and Carrier Detect.  To set the
  113. mask for CTS handshaking you would -     async_msrflow(COM1, B_CTS);
  114. where COM1 == 1 and B_CTS == 0x0010.  These are defined in COMM.H.
  115. Be careful when monitoring the CD bit. If you set the bit to monitor this
  116. signal and a carrier is not present all bytes transmitted will go to the tx
  117. buffer and no further (this includes modem dial commands, etc).  If you want to
  118. stop transmitting if CD is lost set the bit after CD is in its TRUE state.
  119.  
  120.  
  121. -------------------------------------------------------------------------------
  122. ASYNC_OPEN -- open a serial communications port.
  123. -------------------------------------------------------------------------------
  124.   Example:
  125.     int         async_open(int, char *, int, int);
  126.     rcode = async_open(port, "2400N81", txbuf_size, rxbuf_size);
  127.  
  128.   Returns:
  129.     R_OK        - the operation was successful
  130.     R_NOPORT    - the port is shown as non-existent in the BIOS data area
  131.     R_BAUDERR   - attempted to set the baud rate higher than 19.2K
  132.     R_PARITYERR - parity indicator in BPDS string wasn't E, O, or N
  133.     R_DTABITERR - data bits were not either 7 or 8
  134.     R_STPBITERR - stop bits were not either 1 or 2
  135.     R_PORTINUSE - attempted to open an already opened port
  136.     R_BADARG    - requested bufr size outside limits or invalid BPDS string
  137.     R_NOMEM     - internal call to MSC's 'malloc' function failed
  138.  
  139. Currently async_open supports COM1 - COM2 so in the example port must be either
  140. 1 or 2.  The string, Baud Parity Data Stop (BPDS string), is used to set the
  141. line parameters.  The size of the transmit and receive buffers is dynamically
  142. allocated by a call to the MSC library's MALLOC function. The maximum size for
  143. either buffer is 32000 bytes and the minimum size is 100 for the tx buffer and
  144. 750 for the rx buffer.
  145.  
  146. -------------------------------------------------------------------------------
  147. ASYNC_RESET -- resets rx error bits in STAT1 byte.
  148. -------------------------------------------------------------------------------
  149.   Example:
  150.     int         async_reset(int);
  151.     rcode = async_reset(port);
  152.  
  153.   Returns:
  154.     R_OK        - operation was successful
  155.     R_NOPORT    - the port hasn't been opened
  156.  
  157. This function resets any rx error conditions that are signaled in the STAT1
  158. byte.  It is the only way to clear the error bits once they are set.  See
  159. async_rx for more information on STAT1.
  160.  
  161.  
  162. -------------------------------------------------------------------------------
  163. ASYNC_RTS -- toggle RTS modem signal.
  164. -------------------------------------------------------------------------------
  165.   Example:
  166.     int         async_rts(int, int);
  167.     rcode = async_rts(port, flag);
  168.  
  169.   Returns:
  170.     R_OK        - operation was successful
  171.     R_NOPORT    - the port hasn't been opened
  172.  
  173. A zero flag will cause the modem signal 'Request to Send' to be brought
  174. to its FALSE state.  This signal is used for handshaking.  A non-zero flag
  175. re-enables the RTS signal.  When a port is first opened the RTS signal will
  176. be set TRUE unless RTSFALSE was defined on the command line when assembling
  177. the ASYNC.ASM module.  The MAKE files included in the ARC do not make that
  178. definition so if you use it RTS will initially be TRUE.
  179.  
  180. -------------------------------------------------------------------------------
  181. ASYNC_RX -- get a character from the receive buffer.
  182. -------------------------------------------------------------------------------
  183.   Example:
  184.     int         async_rx(int);
  185.     stat_and_char = async_rx(port);
  186.  
  187.   Returns:
  188.     Low byte is character read and high byte is STAT1.
  189.     STAT1: 0=rx bufr ovrfl   1=char overrun     2=parity err    3=framing err
  190.            4=break intrpt    5=invalid port     6=rx bufr empty 7=no carrier
  191.  
  192. STAT1 was designed so that it would be equal to 0 if no line type errors have
  193. been detected, the buffer had something in it, and a carrier is present.  If
  194. a call is made to async_rx when the buffer has nothing in it a '\0' will be
  195. returned as the character and bit 6 will be set in STAT1.  Bit 0 of STAT1
  196. will be set if the rx buffer has overflowed.  Bits 1 thru 4 indicate a line
  197. error or a break signal was received on the comm port.  Bit 5 indicates the
  198. comm port hadn't been opened and bit 7 that the carrier has been lost.
  199. The conditions reflected in bits 0-4 indicate that an error of that type has
  200. occurred since the port was opened or since async_reset was called.  Since
  201. the receive is buffered the char read when STAT1 first indicates the condition
  202. is not necessarily the char that triggered the condition.  Once bits 0-4 are
  203. set they remain set until async_reset is called.
  204. The STAT1 byte can be ignored by casting the returned value to the char type.
  205.  
  206.  
  207. -------------------------------------------------------------------------------
  208. ASYNC_RXCNT -- get the number of bytes of unprocessed data in the rx buffer.
  209. -------------------------------------------------------------------------------
  210.   Example:
  211.     int         async_rxcnt(int);
  212.     chars_to_read = async_rxcnt(port);
  213.  
  214.   Returns:
  215.     Number of bytes in the rx buffer that have not been read if successful.
  216.     R_NOPORT    - the port hasn't been opened
  217.  
  218. The R_NOPORT return value is a negative number and a successful return is
  219. always positive so you can't mistakenly interpret an error return as the number
  220. of bytes in the buffer.  Also as long as the port has been opened the error
  221. return will never occur anyway.
  222.  
  223.  
  224. -------------------------------------------------------------------------------
  225. ASYNC_RXFLUSH -- flush the receive buffer.
  226. -------------------------------------------------------------------------------
  227.   Example:
  228.     int         async_rxflush(int);
  229.     rcode = async_rxflush(port);
  230.  
  231.   Returns:
  232.     R_OK        - operation was successful
  233.     R_NOPORT    - the port hasn't been opened
  234.  
  235. -------------------------------------------------------------------------------
  236. ASYNC_SETBPDS -- set baud, parity, # data bits, # stop bits.
  237. -------------------------------------------------------------------------------
  238.   Example:
  239.     int         async_setbpds(int, char *);
  240.     rcode = async_setbpds(port, bpds_string);
  241.  
  242.   Returns:
  243.     R_OK        - operation was successful
  244.     R_NOPORT    - the port hasn't been opened
  245.     R_BAUDERR   - attempted to set the baud rate higher than 19.2K
  246.     R_PARITYERR - parity indicator in BPDS string wasn't E, O, or N
  247.     R_DTABITERR - data bits were not either 7 or 8
  248.     R_STPBITERR - stop bits were not either 1 or 2
  249.     R_BADARG    - extra characters in BPDS string
  250.  
  251. This function changes the line parameters of an already opened comm port. This
  252. function also changes the STRIP_MASK to no high bit stripping if the number
  253. of data bits is set to 8 (see async_strip for more on the STRIP_MASK).  Mark
  254. parity, and less than 7 data bits are not supported.  The baud rate may be
  255. set to any value between 1 and 19200 baud.
  256. The BPDS string has the form "2400N81", "1200E71", "19200N81", "733N72", etc.
  257. First is the baud rate desired, then E O or N for type of parity, followed by
  258. the number of data bits, and last the number of stop bits.
  259.  
  260.  
  261. -------------------------------------------------------------------------------
  262. ASYNC_STAT -- get port status information.
  263. -------------------------------------------------------------------------------
  264.   Example:
  265.     int         async_stat(int, int);
  266.     status = async_stat(port, status_mask);
  267.  
  268.   Returns:
  269.     STAT1 - high byte, STAT2 - low byte  if successful
  270.     R_NOPORT    - the port hasn't been opened
  271.  
  272.    STAT1: 0=rx bufr ovrfl   1=char overrun     2=parity err    3=framing err
  273.           4=break intrpt    5=not used         6=rx bufr empty 7=no carrier
  274.    STAT2: 0=XON/OFF in use  1=XOFF received    2=XOFF sent     3=tx buf empty
  275.           4=montr'g CTS     5=montr'g DSR      6=flw hlt actv  7=montr'g CD
  276.  
  277. Information contained in the STAT1 byte is described in async_rx section.
  278. There is one difference which is bit 5 is not used by this function to indi-
  279. cate an invalid port as it is in async_rx.  Bits 0 - 2 of STAT2 return infor-
  280. mation on XON/OFF protocol status.  Bit 3 - the transmit buffer is empty,
  281. bits 4, 5, & 7 - tell which signals the transmit interrupt routine is watching
  282. and will shut down if they go false (set by async_msrflow), bit 6 - indicates
  283. that either XON/OFF protocol is being used and an XOFF was received or one
  284. of the monitored modem signals has gone to the low state.
  285. The status mask passed in the function is anded with STAT1;STAT2 information
  286. before it is returned.  Ex:  To check if XON/OFF protocol is being used you
  287. would use --      if (async_stat(COM1, B_XUSE);      where COM1 = 1 and
  288. B_XUSE is defined in the COMM.H file as 0x0001.
  289.  
  290. -------------------------------------------------------------------------------
  291. ASYNC_STRIP -- set the strip mask for incoming characters.
  292. -------------------------------------------------------------------------------
  293.   Example:
  294.     int         async_strip(int, char);
  295.     rcode = async_strip(port, mask);
  296.  
  297.   Returns:
  298.     R_OK        - operation was successful
  299.     R_NOPORT    - the port hasn't been opened
  300.  
  301. The character passed as the mask to this function is ANDed with all incoming
  302. data. It is automatically preset to 0x7F when using 7 data bits and 0xFF when
  303. using 8 data bits by the async_open and async_setbpds functions.
  304.  
  305.  
  306. -------------------------------------------------------------------------------
  307. ASYNC_TX -- move a character to the transmit buffer.
  308. -------------------------------------------------------------------------------
  309.   Example:
  310.     int         async_tx(int, char);
  311.     free_space = async_tx(port, 'A');
  312.  
  313.   Returns:
  314.     Number of bytes left available in the tx buffer if successful.
  315.     R_TXERR     - the tx buffer was full or the port hadn't been opened
  316.  
  317.  
  318. -------------------------------------------------------------------------------
  319. ASYNC_TXFLUSH -- flush the transmit buffer.
  320. -------------------------------------------------------------------------------
  321.   Example:
  322.     int         async_txflush(int);
  323.     rcode = async_txflush(port);
  324.  
  325.   Returns:
  326.     R_OK        - operation was successful
  327.     R_NOPORT    - the port hasn't been opened
  328.  
  329.  
  330. -------------------------------------------------------------------------------
  331. ASYNC_TXFREE -- get number of bytes of free space left in the tx buffer.
  332. -------------------------------------------------------------------------------
  333.   Example:
  334.     int         async_txfree(int);
  335.     nmbr_chars_that_can_be_txd = async_txfree(port);
  336.  
  337.   Returns:
  338.     Number of bytes of free space left in the transmit buffer.
  339.     R_NOPORT    - the port hasn't been opened
  340.  
  341. This value is also the return value of a call to async_tx.
  342.  
  343. -------------------------------------------------------------------------------
  344. ASYNC_TXIMD -- put a block of data at the head of the transmit buffer.
  345. -------------------------------------------------------------------------------
  346.   Example:
  347.     int         async_tximd(int, char *, int);
  348.     tx_bytes_free = async_tximd(port, data_ptr, count);
  349.  
  350.   Returns:
  351.     Number bytes left available in transmit buffer if successful.
  352.     R_TXERR     - the port hasn't been opened or not enough room in tx buffer
  353.  
  354. This function moves 'count' bytes of data starting at 'data_ptr' to the head
  355. of the transmit buffer.  These bytes will be transmitted ahead of any bytes
  356. already in the buffer and then the bytes already in the buffer will continue
  357. to be transmitted.
  358.  
  359.  
  360. -------------------------------------------------------------------------------
  361. ASYNC_XOFFCLR -- manually clear an XOFF received condition.
  362. -------------------------------------------------------------------------------
  363.   Example:
  364.     int         async_xoffclr(int);
  365.     rcode = async_xoffclr(port);
  366.  
  367.   Returns:
  368.     R_OK        - operation was successful
  369.     R_BADARG    - not using XON/XOFF protocol
  370.     R_NOPORT    - the port hasn't been opened
  371.  
  372. Provides a means to clear an XOFF recieved condition if the sending system
  373. fails to send an XON.
  374.  
  375.  
  376. -------------------------------------------------------------------------------
  377. ASYNC_XONANY -- allow any char received to treated as an XON if XOFF active
  378. -------------------------------------------------------------------------------
  379.   Example:
  380.     int         async_xonany(int, int);
  381.     rcode = async_xonany(port, flag);
  382.  
  383.   Returns:
  384.     R_OK        - operation was successful
  385.     R_BADARG    - not using XON/XOFF protocol
  386.     R_NOPORT    - the port hasn't been opened
  387.  
  388. Passing a non-zero value as the flag in this function causes any character
  389. received to de-activate an XOFF received condition.  A zero value as the flag
  390. will make the protocol treat only the XON character as the XOFF clearing
  391. character.  This is included for the ^S to pause, any key to restart type
  392. setup.
  393.  
  394. -------------------------------------------------------------------------------
  395. ASYNC_XONOFF -- enable/disable use of XON/OFF flow control.
  396. -------------------------------------------------------------------------------
  397.   Example:
  398.     int         async_xonoff(int, int);
  399.     rcode = async_xonoff(port, flag);
  400.  
  401.   Returns:
  402.     R_OK        - operation was successful
  403.     R_NOPORT    - the port hasn't been opened
  404.  
  405. Turns use of XOFF protocol on if flag is non-zero else disables use of XOFF.
  406. If an XOFF is active when disabling protocol use it will be automatically
  407. cleared and transmission will resume.  If an XOFF has been sent when disabling
  408. XOFF protocol use, an XON character is sent and then the protocol is disabled.
  409. The XOFF protocol as implemented by these routines sends an XOFF when the
  410. buffer is within so many bytes of being full rather than a percentage.  The
  411. number of bytes is defined as the variable XOFFCOUNT in ASYNC.H.  The XON is
  412. sent when the number of free bytes in the rx buffer is at least XONCOUNT.
  413. These values are currently about 50 bytes different to prevent repeated sending
  414. of XON's and XOFF's when the buffer is at the threshhold level.  Another
  415. variable defined in ASYNC.H, REPTXOFFVAL, determines how many bytes can be
  416. received after an XOFF is sent before another XOFF is sent. Some systems
  417. allow any character received after getting an XOFF to be interpreted as the
  418. XON signal including another XOFF so setting REPTXOFFVAL too low will effect-
  419. ively disable the protocol.  Also some systems, RBBS, seem to be picky about
  420. when they will accept an XOFF while other systems, PROCOMM, respond instantly.
  421. The values chosen seem to be the most likely to work in all situations.
  422.  
  423.